Styling the Map

An MGLStyle object represents the active map style of an MGLMapView. A style defines both the map’s content and every aspect of its appearance. Styles can be designed in Mapbox Studio and hosted on mapbox.com. MGLStyle provides methods for inspecting and manipulating a style dynamically, with classes and properties that parallel the style JSON format defined by the Mapbox Style Specification.

You set a map view’s active style using the MGLMapView.styleURL property. MGLStyle provides a set of convenience methods that return the URLs of popular Mapbox-designed styles. Once the -[MGLMapViewDelegate mapView:didFinishLoadingStyle:] or -[MGLMapViewDelegate mapViewDidFinishLoadingMap:] method is called, signaling that the style has finished loading, you can use the MGLMapView.style property to obtain the map view’s MGLStyle.

A style primarily consists of the following components:

• Content sources supply content to be shown on the map. Use methods such as -sourceWithIdentifier: and -addSource: to configure the style’s content sources, which are represented by MGLSource objects.
• Style layers manage the layout and appearance of content at specific z-indices in the style. Most kinds of style layers display content provided by a content source. Use methods such as -layerWithIdentifier: and -addLayer: to configure the style’s layers, which are represented by MGLStyleLayer objects.
• Style images are used as icons and patterns in style layers. Use the -setImage:forName: method to register an image as a style image. (Annotations are represented by annotation images rather than style images. To configure an annotation’s appearance, use the -[MGLMapViewDelegate mapView:imageForAnnotation:] method.)
• The style’s light is the light source affecting any 3D extruded fills. Use the light property to configure the style’s light, which is represented by an MGLLight object.

The MGLStyle, MGLSource, MGLStyleLayer, and MGLLight classes are collectively known as the runtime styling API. The active style influences a related API, visible feature querying, which is available through methods such as -[MGLMapView visibleFeaturesInRect:].

Some terminology differs between the Mapbox Style Specification and the various classes associated with MGLStyle. Consult the “Information for Style Authors” guide for an overview of these differences.

An MGLStyleValue object is a generic container for a style attribute value. The layout and paint attribute properties of MGLStyleLayer can be set to MGLStyleValue objects.

The MGLStyleValue class itself represents a class cluster. Under the hood, a particular MGLStyleValue object may be either an MGLConstantStyleValue to represent a constant value or one of the concrete subclasses of MGLStyleFunction to represent a value function. Do not initialize an MGLStyleValue object directly; instead, use one of the class factory methods to create an MGLStyleValue object.

The MGLStyleValue class takes a generic parameter T that indicates the Foundation class being wrapped by this class. Common values for T include:

• NSNumber (for Boolean values and floating-point numbers)
• NSValue (for CGVector, NSEdgeInsets, UIEdgeInsets, and enumerations)
• NSString
• NSColor or UIColor
• NSArray

An MGLLight object represents the light source for extruded geometries in MGLStyle.